Module for the management of\n viewables. These are logical, multidimensional\n arrays and graph structures whose elements can be accessed\n globally for visualisation purposes. The creation,\n destruction and modification of viewables and their\n contents can be monitored by visualisation clients.
\n\n The library lib(graph_algorithms) contains\n predicates to create and manipulate graph structures.\n\n
Viewables are created using viewable_create/2/3/4\n and last until this call is\n backtracked over. During its lifetime, a viewable is said to be\n existent. This can be tested with\n viewable/1, which can also be used to enumerate all\n existent viewables.
One or more of the dimensions of a viewable can\n optionally be flexible in size while the viewable is\n existent. This allows new elements to be added to the\n viewable, using viewable_expand/3/4. The\n fixity of a dimension denotes whether it is fixed\n or flexible. In the case of graph typed viewables, the\n fixity refers to the ability to add new nodes and/or edges\n to the graph. Currently only fixed graphs are\n supported.\n\n
A viewable is given a type when it is created. For\n array types, this specifies the number of dimensions, the\n fixity of each dimension and the type of viewable elements\n which the viewable can contain. For graph types, this\n simply specifies whether the graph structure (number of\n nodes, edge direction etc) may be modified during the\n viewables lifetime. An existent viewable's type can be\n retrieved using viewable_type/2, and its\n current sizes of the dimensions can be retrieved using\n viewable_size/2.
viewable_create/2/3/4 and\n viewable_expand/3/4 succeed with any arguments. It is\n therefore reasonable to leave these predicates in your code even\n when not visualising.viewable/1, viewable_size/2 and\n viewable_type/2 fail whatever the arguments. If\n these predicates are used (normally they should not be\n necessary) the possibility of failure should be taken into\n account.NOTE:When there are no registered visualisation clients,\n this predicate fails with all arguments, and has no effect.
\n\n\n If ViewableName is instantiated, tests whether\n ViewableName is the name of an existent viewable. If not,\n ViewableName is successively instantiated to the names of all\n existent viewables."), fail_if : "Fails if ViewableName is not / cannot be instantiated to the name of an existent viewable.", exceptions : [4 : "ViewableName is not an atom, string or free variable"], resat : yes, eg : "\n\n[Assuming that at least one visualisation client is registered]\n\n Success:\n\n viewable_create(my_viewable, [X,Y,Z], array([fixed], any)), \n viewable(my_viewable).\n\n\n Failure:\n\n viewable(non_viewable)\n\n\n Exception raised:\n\n viewable(123).\n [raises error 4].\n", see_also : [viewable_create / 2, viewable_create / 3]]). :- comment(viewable_create / 2, [amode : viewable_create(?, +), args : ["ViewableName" : "A string or atom; the name of the new viewable.", "Elements" : "A possibly nested list or array (as created for example by dim/2)."], summary : "Create a viewable.", eg : "\n\n[Assuming that at least one visualisation client is registered]\n\n Success:\n\n viewable_create(viewable1, [X, Y, Z]).\n\n viewable_create(\"viewable1\", [](X, Y, Z)).\n\n viewable_create(m, []).\n\n viewable_create(var23, [[],[],[]]).\n\n viewable_create(var315, []([]([](R, T, [E, X, Y]), \n [](W, T, grok(D))), \n\t\t\t\t []([](A, B, C),\n\t\t\t\t [](R, E, W)))).\n\n\n\n Exceptions raised:\n\n viewable_create(2, [x,y,z]).\n [gives error 4] \n\n viewable_create(v1, [x,y,z]), \n viewable_create(v1, [x,y,z]).\n [gives error 1] \n\n viewable_create(v1, _).\n [gives error 1] \n\n\n\t\t\t\t ", desc : html("\n\nNOTE:When there are no registered visualisation clients,\n this predicate succeeds with any arguments, and has no effect.
\n\n\tThis predicate creates a new viewable by specifying its name and\n\telements. The predicate will try to guess the number of dimensions\n\tfor the new viewable from the level of nesting in\n\tElements. All dimensions are set tofixed so\n\tthey cannot be expanded later. The element type is set to\n\tany. For more control over the number and fixity of\n\tdimensions and the element type, use\n\tviewable_create/3.\n\n In other ways the predicate behaves just like\n viewable_create/3. See the documentation for that\n predicate for more details. "), see_also : [viewable_create / 3, viewable_expand / 3], exceptions : [4 : "ViewableName is not an atom, string or free variable.", 1 : "ViewableName is the name of an existent viewable.", 1 : "Elements is not a nested list or array."], resat : no]).
:- comment(viewable_create / 3, [amode : viewable_create(?, +, ++), args : ["ViewableName" : "A string or atom; the name of the new viewable.", "Elements" : "A list nested to at least a depth equal to the number of dimensions, an array with sufficient dimensions (as created for example by dim/2) or graph structure.", "Type" : "A ground term which is a valid viewable type. "], summary : "Create a viewable, specifying type.", eg : "\n\n[Assuming that at least one visualisation client is registered] \n\n Success:\n\n viewable_create(viewable1, [X, Y, Z], array([fixed], any)).\n\n lib(fd), fd:([X, Y, Z]::1..10), \n viewable_create(viewable1, [X, Y, Z], array([fixed], numeric_bounds)).\n\n viewable_create(viewable1, [3.2, 5.00__5.01, 7], \n array([fixed], numeric_bounds)).\n\n viewable_create(\"viewable1\", [](X, Y, Z), array([flexible], any)).\n\n viewable_create(m, [], array([flexible], any)).\n\n viewable_create(var23, [[],[],[]], array([fixed, flexible], any)).\n\n viewable_create(var315, []([]([](R, T, [E, X, Y]), \n [](W, T, grok(D))), \n\t\t\t\t []([](A, B, C),\n\t\t\t\t [](R, E, W))), \n\t\t array([fixed, flexible, flexible], any)).\n\n viewable_create(m,[[],[],[]],array([fixed, flexible, flexible],any)).\n [Note: the initial size of this viewable would be 3 x 0 x 0]\n\n lib(graph_algorithms),\n make_graph(3,[e(1,2,e1), e(2,3,e2), e(1,3,e3)], Graph),\n viewable_create(m, Graph, graph(fixed)).\n [Note: the node will be labelled with the numbers '1', '2' and '3',\n the edges labelled 'e1', 'e2' and 'e3']\n \n lib(graph_algorithms),\n make_graph_symbolic([](n1,n2,n3),[edge(n1,n2,e1), edge(n2,n3,e2), edge(n1,n3,e3)], Graph),\n viewable_create(m, Graph, graph(fixed)).\n [Note: the node will be labelled with the strings 'n1', 'n2' and 'n3',\n the edges labelled 'e1', 'e2' and 'e3']\n\n lib(eplex_with_ic),\n eplex_instance(my_instance),\n my_instance: eplex_solver_setup(min(X)),\n viewable_create(eplex,[X,Y],array([fixed],changeable(my_instance,numeric_bounds))),\n viewable_create(ic,[X,Y],array([fixed],numeric_bounds)),\n my_instance: (X+Y >= 3),\n my_instance: (X-2*Y =:= 0),\n my_instance: eplex_solve(Cost). \n [Note: this creates two viewables, one showing the solution as\n assigned by eplex, the other showing the ic bounds]\n\n lib(s_eplex),\n eplex_instance(my_instance),\n my_instance: eplex_solver_setup(min(X)),\n viewable_create(eplex,[X,Y],array([fixed],changeable(my_instance,numeric_bounds))),\n my_instance: (X+Y >= 3),\n my_instance: (X-2*Y =:= 0),\n my_instance: eplex_solve(Cost). \n [Note: this creates a single viewable using the standalone eplex\n library and shows how to visualise the bounds stored in the external\n solver]\n\n\n Exceptions raised:\n\n viewable_create(2, [x,y,z], array([fixed], any)).\n [gives error 4] \n\n viewable_create(v1, [x,y,z], array([fixed], any)), \n viewable_create(v1, [x,y,z], array([fixed], any)).\n [gives error 1] \n\n viewable_create(v1, _, array([fixed], any)).\n [gives error 1] \n\n viewable_create(v1, [x,y,g], array([fixed, fixed], any)).\n [gives error 1] \n\n viewable_create(v1, [x,y,x], array([], any)).\n [gives error 1] \n\n viewable_create(v1, [x,y,x], slorg([fixed], any)).\n [gives error 1] \n\n viewable_create(v1, [x,y,x], nurg).\n [gives error 1] \n\n viewable_create(v1, [x,y,x], numeric_bounds).\n [gives error 5] \n\t\t\t\t ", desc : html("\n\n NOTE:When there are no registered visualisation clients,\n this predicate succeeds with any arguments, and has no effect.
\n\n\tThis predicate creates a new viewable by specifying its name,\n\telements and type. At present the type must be of the form\n\tarray(FixityList, ElementType) or graph(fixed) wherefixed or\n\tflexible specifying the fixity for each\n\tdimension. The fixity denotes whether the dimension's size is\n\tfixed or may vary during the time when the viewable is\n\texistent.any\n\twhich includes any ECLiPSe termnumeric_bounds which includes any ground number,\n\tinteger fd variables, ic variables\n\tand range variables (including eplex\n\tand ria variables). changeable(Module,Type) which indicates that the\n\tvalue should be accessed through the changeable\n\tinterface of the given Module\n\t(eg. changeable(eplex_instance,any) indicates that the value\n\tis ths solution assigned to the variable by the given\n\teplex_instance). The Type parameter can be any\n\tof the other ElementTypes in this list.viewable_create/3, the viewable is destroyed, and\n\tvisualisation clients are also notified of this. \n\n\tViewableName is a global handle which can be used to\n\taccess the viewable while it is existent. If ViewableName\n\tis a variable, it is instantiated to an atom. The atom is unique in\n\tthe sense that no two existent viewables will share the same name\n\tat any point during the lifetime of the ECLiPSe engine.
\n\n For array types, the number of dimensions is specified by the\n length of FixityList in Type. Elements\n is a nested list or array. The depth of nesting is usually at\n least the number of dimensions specified in FixityList.\n However, dimensions with an initial size of 0 are also\n allowed, and these can implicitly contain an arbitrary number\n of further dimensions, also assumed to be of initial size\n 0. So for example an Elements argument of\n [[],[],[]] or []([],[],[]) can be\n used with a FixityList of [fixed,\n flexible], giving an initial size of 3 x 0, or used\n with a FixityList of [fixed, flexible,\n flexible, flexible], giving an initial size of 3 x 0 x\n 0 x 0. Be sure to make any initially empty dimensions\n flexible! Elements must also be regular: each inner\n list / array at the same level of nesting must be the same\n length, down to the level equal to the number of dimensions.\n\n
viewable_create/3 sets location names (e.g. row/column\n names) to \"1\", \"2\", etc. For more control over location names use \n viewable_create/4.
NOTE:When there are no registered visualisation clients,\n this predicate succeeds with any arguments, and has no effect.
\n\nThis predicate works exactly the same as\n viewable_create/3 except that you have the added\n ability to set location names (e.g. row/column names) for\n arrays and to indicate which elements of the edge info\n structure should be attached to edge labels for graphs.\n\n
For array type viewables the LocNamesList argument\n should be a list as long as the number of dimensions in the\n viewable. The ith element LocNames of\n LocNamesList should be a list whose length is equal\n to the size of the ith dimension of the new viewable. The jth\n element of LocNames should be a ground string and\n this will become the name of the jth location of the ith\n dimension.
\n\nFor graph type viewables the LocNamesList argument\n should be a list of the following form.\n\n
\n[\n node_property([0->[name(NodeInfoName), label]]),\n edge_property([Index->[name(EdgeInfoName), label]])\n]\n\n\n Where
NodeInfoName is a meaningful name for the\n information to be displayed at the nodes in the graph. eg. If\n the graph represented a computer network, the nodes may show\n individual machine names. In such a case, \"machine\n name\" would be a likely candidate for the NodeInfoName\n argument. Similarly EdgeInfoName refers to the\n information associated with edge labels.\n\n The Index argument specifies which part of the\n edge info field should be shown on edges. 0:The whole edge\n info structure. N:The Nth argument of the edge info\n structure. [...,I,J,K]:The Kth argument of the Jth argument\n of the Ith argument... of the edge info structure. See below\n for examples.\n\n
For a more detailed description of creating viewables, refer to the\n documentation for viewable_create/3.
NOTE:When there are no registered visualisation clients,\n this predicate succeeds with any arguments, and has no effect.
\n\n\n\nA viewable which has a flexible dimension (see\n viewable_create/3) may be expanded along that dimension\n by adding new elements. The dimension must have been declared\n flexible when the viewable was first created. The\n ExtraElements argument is of the same format as the\n Elements argument of viewable_create/3.
The number and size of the dimensions of ExtraElements\n depends on the number and size of dimensions of the viewable being\n expanded. ExtraElements should have one less dimension than\n the viewable -- dimension DimensionNumber should be\n missing. The remaining dimensions should have the same sizes as the\n corresponding dimensions in the viewable.
\n\nFor example, a viewable of size 3 x 0 x 0 with all dimensions\n flexible, can be expanded along dimenson 3 using an\n ExtraElements argument of []([], [], []) which has size 3 x\n 0. The viewable would then have size 3 x 0 x 1. It could then be\n expanded along dimension 1 using [] as\n ExtraElements since [] can implicitly have the\n size 0 x 1. The viewable would then have the size 4 x 0 x 1. Then\n dimension 2 could be expanded using [[W],[X],[Y],[Z]]\n for ExtraElements as this has size 4 x 1. The final size of\n the viewable would then be 4 x 1 x 1.
The extra viewable elements must each also conform to the element\n type specified when the viewable was created.
\n\nNote that when the viewable has one dimension, the\n ExtraElements argument will simply become the new element\n itself.
\n\nviewable_expand/3 sets the name of the new location \n (e.g. the column or row name) to its number as a string. For example, \n adding a third row using viewable_expand/3 will result\n in the row being named \"3\". For more control over the name of the new\n location use viewable_expand/4.
\n\n"), fail_if : "Fails if ViewableName is not the name of an existent viewable, or if the requested dimension of the viewable is not flexible.", exceptions : [4 : "ViewableName is not a string or atom", 5 : "DimensionNumber is not a ground integer", 6 : "DimensionNumber is not positive, or exceeds the viewable's number of dimensions", 1 : "ExtraElements is not a regular nested list or array of the correct size/dimensions", 5 : "ExtraElements contains elements which do not conform to the element type of the viewable"], resat : no, eg : "\n\n[Assuming that at least one visualisation client is registered]\n\n Success:\n\n viewable_create(v1, [[X, Y, Z], [A, B, C]], \n \t array([flexible, fixed], any)), \n viewable_expand(v1, 1, [R, S, T]).\n\n lib(fd), fd:([X, Y, Z, R] :: 1..10), \n viewable_create(v1, [X, Y, Z], array([flexible], numeric_bounds)),\n viewable_expand(v1, 1, R).\n \n viewable_create(v1, []([](X, Y, Z), [](A, B, C)), \n \t array([fixed, flexible], any)), \n viewable_expand(v1, 2, [R, S]).\n\n\n viewable_create(v1, [[], [], []], \n\t\t array([flexible, flexible, flexible], any)),\n viewable_expand(v1, 3, []([], [], [])), \n viewable_expand(v1, 1, []), \n viewable_expand(v1, 2, [[W], [X], [Y], [Z]]), \n viewable_size(v1, Size).\n [gives Size = [4,1,1]]\n\n viewable_create(v1, [], array([flexible], any)), \n viewable_expand(v1, 1, F), \n viewable_expand(v1, 1, G),\n viewable_size(v1, Size).\n [gives Size = [2]]\n \n \n\n\n Failure:\n\n viewable_expand(no, 2, [R, S]).\n\n\n viewable_create(v1, [[X, Y, Z], [A, B, C]], \n\t array([fixed, flexible], any)), \n viewable_expand(v1, 1, [R, S, T]).\n\n\n viewable_create(v1, [[X, Y, Z], [A, B, C]], \n\t array([flexible, fixed], any)), \n viewable_expand(v1, 2, [R, S]).\n\n\n\n Exceptions raised:\n\n viewable_create(v1, [[X, Y, Z], [A, B, C]], \n\t array([flexible, fixed], any)), \n viewable_expand(_, 1, [R, S, T]).\n [gives error 4]\n\n viewable_create(v1, [[X, Y, Z], [A, B, C]], \n\t array([flexible, fixed], any)), \n viewable_expand(v1, _, [R, S, T]).\n [gives error 5]\n\n viewable_create(v1, [[X, Y, Z], [A, B, C]], \n array([flexible, fixed], any)), \n viewable_expand(v1, 3, [R, S, T]).\n [gives error 6]\n\n viewable_create(v1, []([](X, Y, Z), [](A, B, C)), \n\t array([fixed, flexible], any)), \n viewable_expand(v1, 2, _).\n [gives error 1]\n\n viewable_create(v1, [[X, Y, Z], [A, B, C]], \n\t array([flexible, fixed], any)), \n viewable_expand(v1, 1, [R, S, T, Q]).\n [gives error 1]\n\n lib(fd), fd:([X, Y, Z] :: 1..10), \n viewable_create(v1, [X, Y, Z], array([flexible], numeric_bounds)),\n viewable_expand(v1, 1, an_atom)\n [gives error 5]\n\n\n\n", see_also : [viewable_expand / 4, viewable_create / 3, viewable_size / 2, viewable_type / 2]]). :- comment(viewable_expand / 4, [amode : viewable_expand(++, ++, +, ++), args : ["ViewableName" : "A string or atom; the name of an existent viewable", "DimensionNumber" : "An integer: the number of the dimension to be enlarged.", "ExtraElements" : "A nested list or an array of the right size/dimensions, containing the new viewable elements.", "LocName" : "A string: the name of the new location."], summary : "Expand a dimension of a viewable by adding new elements, specifying the name of the new location.", desc : html("\n\n
NOTE:When there are no registered visualisation clients,\n this predicate succeeds with any arguments, and has no effect.
\n\nThis predicate behaves exactly the same as viewable_expand/3 except that you have the added ability to name the new location of the expanded dimension. LocName is a string which becomes the name for the new location.
viewable_expand/3. \n\n"), fail_if : "Fails if ViewableName is not the name of an existent viewable, or if the requested dimension of the viewable is not flexible.", exceptions : [4 : "ViewableName is not a string or atom", 5 : "DimensionNumber is not a ground integer", 6 : "DimensionNumber is not positive, or exceeds the viewable's number of dimensions", 1 : "ExtraElements is not a regular nested list or array of the correct size/dimensions", 5 : "ExtraElements contains elements which do not conform to the element type of the viewable", 5 : "LocName is not a string"], resat : no, eg : "\n\n[Assuming that at least one visualisation client is registered]\n\n viewable_create(v1, [[X, Y, Z], [A, B, C]], \n \t array([flexible, fixed], any)), \n viewable_expand(v1, 1, [R, S, T], \"barg\").\n\n This will add to the 2 x 3 viewable a third row, named \"barg\".\n\n viewable_create(v1, [[X, Y, Z], [A, B, C]], \n \t array([fixed, flexible], any)), \n viewable_expand(v1, 2, [Q, P], \"zatch\").\n\n This will add to the 2 x 3 viewable a fourth column, named \"zatch\".\n\n\n", see_also : [viewable_expand / 3, viewable_create / 4, viewable_size / 2, viewable_type / 2]]).
:- comment(viewable_size / 2, [amode : viewable_size(++, ?), args : ["ViewableName" : "A string or atom: the name of an existent viewable", "SizeList" : "A list of integers: each is the current size of a dimension"], summary : "Query the sizes of the dimensions of an existent viewable.", desc : html(" NOTE:When there are no registered visualisation clients, this\n predicate fails with all arguments, and has no effect.
\n\nIf ViewableName is the name of an existent viewable,\n\t SizeList is unified with a list of integers, each\n\t integer being the number of elements in one of the viewable's\n\t dimensions."), fail_if : "Fails if ViewableName is not\n\t instantiated to the name of an existent viewable, or if\n\t SizeList fails to unify with the list of dimension sizes.\n\n", exceptions : [4 : "ViewableName is not a string or an atom", 5 : "SizeList is not a free variable or list or contains one or more elements which is not a free variable or an integer"], resat : no, eg : "\n\n[Assuming that at least one visualisation client is registered]\n\n\tSuccess:\n\n\tviewable_create(v1, [], \n\t\t\tarray([flexible, flexible, flexible], any)), \n\tviewable_size(v1, X).\n [gives X = [0,0,0]]\n\n\tviewable_create(v1, []([](R,S), [](Q,W)), \n\t\t\tarray([fixed, fixed], any)), \n\tviewable_size(v1, X).\n [gives X = [2,2]]\n\n\n\tFailure:\n\n\tviewable_size(no, X).\n\n\tviewable_create(v1, []([](R,S), [](Q,W)), \n\t\t\tarray([fixed, fixed], any)), \n\tviewable_size(v1, [1,2]).\n\n\n\n Exceptions raised:\n\n\tviewable_size(_, X).\n [gives error 4]\n\n\tviewable_size(123, X).\n [gives error 4]\n\n\tviewable_create(v1, [X, Y, Z]), \n\tviewable_size(v1, q).\n [gives error 5]\n\n\tviewable_create(v1, [X, Y, Z]), \n\tviewable_size(v1, [a]).\n [gives error 5]\n\n", see_also : [viewable_create / 3, viewable_expand / 3, viewable_type / 2]]). :- comment(viewable_type / 2, [amode : viewable_type(++, ?), args : ["ViewableName" : "A string or atom: the name of an existent viewable", "Type" : "The type of the viewable. "], summary : "Query the type of an existent viewable.", desc : html("\n\n
NOTE:When there are no registered visualisation clients,\n this predicate fails with all arguments, and has no effect.
\n\nIf ViewableName is the name of an existent viewable,\n Type is unified with its type. See\n viewable_create/3 for a discussion of valid viewable\n types.